fix: Partial block to block conversion in HTML export #2089

matthewlipski · 2025-10-08T18:31:06Z

Summary

This PR fixes numerous runtime errors that could occur when passing PartialBlock arrays to blocksToFullHTML/blocksToHTMLLossy/blocksToMarkdownLossy rather than Block arrays. This is because we need full Block objects when doing the conversion as this is the type that gets passed to render/toExternalHTML, and were not doing the conversion properly.

Rationale

This issue wasn't really noticed as it's rare that a block's render/toExternalHTML functions will ever access anything aside from the block's props, which were previously correctly getting converted. However, it's a pretty major issue as the object being passed to those functions was basically half missing.

Changes

Implemented partialBlockToBlock function and used it in serializeBlocksInternalHTML/serializeBlocksExternalHTML.

Impact

N/A

Testing

Added a custom block to the unit test editor schema which validates that the block passed to render/toExternalHTML is of the correct shape. Added unit tests which export this block but specifically omit fields to ensure that they are fixed during the export.

Screenshots/Video

Checklist

Code follows the project's coding standards.
Unit tests covering the new feature have been added.
All existing tests pass.
The documentation has been updated to reflect the new feature

Additional Notes

vercel · 2025-10-08T18:31:12Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
blocknote	Ready	Preview	Oct 13, 2025 10:44am
blocknote-website	Ready	Preview	Oct 13, 2025 10:44am

YousefED · 2025-10-08T20:19:07Z

Thanks @matthewlipski . Could you give some background on how you ran into this / what was the background / trigger / scenario you're solving?

Asking this because;

I was revisiting the zod propschemas today, this seems relevant
maybe we should zoom out and look at the concept of "partial" more holistically

packages/core/src/api/exporters/html/util/serializeBlocksExternalHTML.ts

packages/core/src/api/partialBlockToBlock.ts

packages/core/src/api/partialBlockToFullBlock.ts

packages/core/src/api/partialBlockToBlock.ts

matthewlipski · 2025-10-09T12:56:32Z

Thanks @matthewlipski . Could you give some background on how you ran into this / what was the background / trigger / scenario you're solving?

Asking this because;

I was revisiting the zod propschemas today, this seems relevant

maybe we should zoom out and look at the concept of "partial" more holistically

I originally ran into this issue recently when working on #2071. The toggle list item uses block.children in its render function, and after adding the block to our list/default block tests, they were throwing an error. This is because serializeBlocksInternalHTML/serializeBlocksExternalHTML were only converting the props, and if no children were passed, block.children would be undefined while the toggle block's render expected an array.

In that PR, I made a quick fix for the children but left the other fields (id, type, and content) unconverted were since they were out of scope. But the whole conversion seemed like a major oversight so I wanted to get this PR out right away. Admittedly though, there are not many use cases I can think of where a block's ID or content should change how it's rendered/exported.

pkg-pr-new · 2025-10-10T10:08:36Z

Open in StackBlitz

@blocknote/ariakit

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/ariakit@2089

@blocknote/code-block

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/code-block@2089

@blocknote/core

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/core@2089

@blocknote/mantine

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/mantine@2089

@blocknote/react

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/react@2089

@blocknote/server-util

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/server-util@2089

@blocknote/shadcn

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/shadcn@2089

@blocknote/xl-ai

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-ai@2089

@blocknote/xl-docx-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-docx-exporter@2089

@blocknote/xl-email-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-email-exporter@2089

@blocknote/xl-multi-column

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-multi-column@2089

@blocknote/xl-odt-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-odt-exporter@2089

@blocknote/xl-pdf-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-pdf-exporter@2089

commit: 03fd40e

…ontent`

packages/core/src/util/table.ts

YousefED

Thanks for working on this!

A couple of points regarding the PR itself:

It looks like several of the new functions overlap with existing code particularly in partialBlockToBlockForTesting, util/table.ts, and blockToNode.ts. It might be worth checking if we can reuse or consolidate some of these before merging.
Many of the helper functions in partialBlockToFullBlock seem like strong candidates for granular unit tests. It's nice that cases are covered in formatConversion-tests, but those tests feel more integration-level. Maybe this is part of a bigger discussion re. test setup (cc @nperez0111)

However, my main takeaway is that the whole concept of PartialBlocks is adding unnecessary complexity to the codebase. We can see if we can restrict PartialBlock usage to higher-level methods in BlockNoteEditor.

If this fix isn't urgent, maybe we hold off until we've validated that broader direction? wdyt?

matthewlipski · 2025-10-13T10:40:56Z

Yeah I think it makes sense to wait and see if this is really needed, since it's a decent chunk of code, especially if we add more tests. Are there any major features/refactors that we could bundle this investigation with?

Fixed partial block to block conversion in HTML export

6f0d67e